IRIX Base Documentation 1998 November/IRIX 6.5.2 Base Documentation November 1998.img/usr/share/catman/p_man/cat3c/ctime.z/ctime

Text File | 1998-10-20 | 23KB | 263 lines

ccccttttiiiimmmmeeee((((3333CCCC))))                                                            ccccttttiiiimmmmeeee((((3333CCCC))))



NNNNAAAAMMMMEEEE
     _cccc_tttt_iiii_mmmm_eeee, _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee, _gggg_mmmm_tttt_iiii_mmmm_eeee, _aaaa_ssss_cccc_tttt_iiii_mmmm_eeee, _tttt_zzzz_ssss_eeee_tttt, _cccc_tttt_iiii_mmmm_eeee______rrrr, _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee______rrrr, _gggg_mmmm_tttt_iiii_mmmm_eeee______rrrr,
     _aaaa_ssss_cccc_tttt_iiii_mmmm_eeee______rrrr - convert date and time to string

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_tttt_iiii_mmmm_eeee_...._hhhh_>>>>

     _cccc_hhhh_aaaa_rrrr _****_cccc_tttt_iiii_mmmm_eeee _((((_cccc_oooo_nnnn_ssss_tttt _tttt_iiii_mmmm_eeee______tttt _****_cccc_llll_oooo_cccc_kkkk_))))_;;;;

     _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_mmmm _****_llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee _((((_cccc_oooo_nnnn_ssss_tttt _tttt_iiii_mmmm_eeee______tttt _****_cccc_llll_oooo_cccc_kkkk_))))_;;;;

     _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_mmmm _****_gggg_mmmm_tttt_iiii_mmmm_eeee _((((_cccc_oooo_nnnn_ssss_tttt _tttt_iiii_mmmm_eeee______tttt _****_cccc_llll_oooo_cccc_kkkk_))))_;;;;

     _cccc_hhhh_aaaa_rrrr _****_aaaa_ssss_cccc_tttt_iiii_mmmm_eeee _((((_cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_mmmm _****_tttt_mmmm_))))_;;;;

     _eeee_xxxx_tttt_eeee_rrrr_nnnn _tttt_iiii_mmmm_eeee______tttt _tttt_iiii_mmmm_eeee_zzzz_oooo_nnnn_eeee_,,,, ______tttt_iiii_mmmm_eeee_zzzz_oooo_nnnn_eeee_,,,, _aaaa_llll_tttt_zzzz_oooo_nnnn_eeee_,,,, ______aaaa_llll_tttt_zzzz_oooo_nnnn_eeee_;;;;

     _eeee_xxxx_tttt_eeee_rrrr_nnnn _iiii_nnnn_tttt _dddd_aaaa_yyyy_llll_iiii_gggg_hhhh_tttt_,,,, ______dddd_aaaa_yyyy_llll_iiii_gggg_hhhh_tttt_;;;;

     _eeee_xxxx_tttt_eeee_rrrr_nnnn _cccc_hhhh_aaaa_rrrr _****_tttt_zzzz_nnnn_aaaa_mmmm_eeee_[[[[_2222_]]]]_,,,, _****______tttt_zzzz_nnnn_aaaa_mmmm_eeee_[[[[_2222_]]]]_;;;;

     _vvvv_oooo_iiii_dddd _tttt_zzzz_ssss_eeee_tttt _((((_vvvv_oooo_iiii_dddd_))))_;;;;

     _cccc_hhhh_aaaa_rrrr _****_cccc_tttt_iiii_mmmm_eeee______rrrr _((((_cccc_oooo_nnnn_ssss_tttt _tttt_iiii_mmmm_eeee______tttt _****_cccc_llll_oooo_cccc_kkkk_,,,, _cccc_hhhh_aaaa_rrrr _****_bbbb_uuuu_ffff_))))_;;;;

     _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_mmmm _****_llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee______rrrr _((((_cccc_oooo_nnnn_ssss_tttt _tttt_iiii_mmmm_eeee______tttt _****_cccc_llll_oooo_cccc_kkkk_,,,,
          _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_mmmm _****_rrrr_eeee_ssss_uuuu_llll_tttt_))))_;;;;

     _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_mmmm _****_gggg_mmmm_tttt_iiii_mmmm_eeee______rrrr _((((_cccc_oooo_nnnn_ssss_tttt _tttt_iiii_mmmm_eeee______tttt _****_cccc_llll_oooo_cccc_kkkk_,,,,
          _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_mmmm _****_rrrr_eeee_ssss_uuuu_llll_tttt_))))_;;;;

     _cccc_hhhh_aaaa_rrrr _****_aaaa_ssss_cccc_tttt_iiii_mmmm_eeee______rrrr _((((_cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt_mmmm _****_tttt_mmmm_,,,, _cccc_hhhh_aaaa_rrrr _****_bbbb_uuuu_ffff_))))_;;;;

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _cccc_tttt_iiii_mmmm_eeee, _cccc_tttt_iiii_mmmm_eeee______rrrr, _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee, _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee______rrrr, _gggg_mmmm_tttt_iiii_mmmm_eeee, and _gggg_mmmm_tttt_iiii_mmmm_eeee______rrrr accept
     arguments of type _tttt_iiii_mmmm_eeee______tttt, pointed to by _cccc_llll_oooo_cccc_kkkk, representing the time in
     seconds since 00:00:00 UTC, January 1, 1970.  _cccc_tttt_iiii_mmmm_eeee and _cccc_tttt_iiii_mmmm_eeee______rrrr return a
     pointer to a 26-character string as shown below.  Time zone and daylight
     savings corrections are made before the string is generated.  The fields
     are constant in width:

           Fri Sep 13 00:00:00 1986\n\0

     _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee, _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee______rrrr, _gggg_mmmm_tttt_iiii_mmmm_eeee, and _gggg_mmmm_tttt_iiii_mmmm_eeee______rrrr return pointers to _tttt_mmmm
     structures, described below.  _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee and _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee______rrrr correct for the
     main time zone and possible alternate (``daylight savings'') time zone;
     _gggg_mmmm_tttt_iiii_mmmm_eeee and _gggg_mmmm_tttt_iiii_mmmm_eeee______rrrr convert directly to Coordinated Universal Time (UTC),
     which is the time the UNIX system uses internally.

     _aaaa_ssss_cccc_tttt_iiii_mmmm_eeee and _aaaa_ssss_cccc_tttt_iiii_mmmm_eeee______rrrr convert a _tttt_mmmm structure to a 26-character string, as
     shown in the above example, and returns a pointer to the string.




                                                                        PPPPaaaaggggeeee 1111






ccccttttiiiimmmmeeee((((3333CCCC))))                                                            ccccttttiiiimmmmeeee((((3333CCCC))))



     Declarations of all the functions and externals, and the _tttt_mmmm structure,
     are in the _tttt_iiii_mmmm_eeee_...._hhhh header file.  The structure declaration is:

          _ssss_tttt_rrrr_uuuu_cccc_tttt    _tttt_mmmm _{{{{
               _iiii_nnnn_tttt  _tttt_mmmm______ssss_eeee_cccc_;;;;   _////_**** _ssss_eeee_cccc_oooo_nnnn_dddd_ssss _aaaa_ffff_tttt_eeee_rrrr _tttt_hhhh_eeee _mmmm_iiii_nnnn_uuuu_tttt_eeee _---- _[[[[_0000_,,,, _6666_1111_]]]] _****_////
                                   _////_**** _ffff_oooo_rrrr _llll_eeee_aaaa_pppp _ssss_eeee_cccc_oooo_nnnn_dddd_ssss _****_////
               _iiii_nnnn_tttt  _tttt_mmmm______mmmm_iiii_nnnn_;;;;   _////_**** _mmmm_iiii_nnnn_uuuu_tttt_eeee_ssss _aaaa_ffff_tttt_eeee_rrrr _tttt_hhhh_eeee _hhhh_oooo_uuuu_rrrr _---- _[[[[_0000_,,,, _5555_9999_]]]] _****_////
               _iiii_nnnn_tttt  _tttt_mmmm______hhhh_oooo_uuuu_rrrr_;;;;  _////_**** _hhhh_oooo_uuuu_rrrr _ssss_iiii_nnnn_cccc_eeee _mmmm_iiii_dddd_nnnn_iiii_gggg_hhhh_tttt _---- _[[[[_0000_,,,, _2222_3333_]]]] _****_////
               _iiii_nnnn_tttt  _tttt_mmmm______mmmm_dddd_aaaa_yyyy_;;;;  _////_**** _dddd_aaaa_yyyy _oooo_ffff _tttt_hhhh_eeee _mmmm_oooo_nnnn_tttt_hhhh _---- _[[[[_1111_,,,, _3333_1111_]]]] _****_////
               _iiii_nnnn_tttt  _tttt_mmmm______mmmm_oooo_nnnn_;;;;   _////_**** _mmmm_oooo_nnnn_tttt_hhhh_ssss _ssss_iiii_nnnn_cccc_eeee _JJJJ_aaaa_nnnn_uuuu_aaaa_rrrr_yyyy _---- _[[[[_0000_,,,, _1111_1111_]]]] _****_////
               _iiii_nnnn_tttt  _tttt_mmmm______yyyy_eeee_aaaa_rrrr_;;;;  _////_**** _yyyy_eeee_aaaa_rrrr_ssss _ssss_iiii_nnnn_cccc_eeee _1111_9999_0000_0000 _****_////
               _iiii_nnnn_tttt  _tttt_mmmm______wwww_dddd_aaaa_yyyy_;;;;  _////_**** _dddd_aaaa_yyyy_ssss _ssss_iiii_nnnn_cccc_eeee _SSSS_uuuu_nnnn_dddd_aaaa_yyyy _---- _[[[[_0000_,,,, _6666_]]]] _****_////
               _iiii_nnnn_tttt  _tttt_mmmm______yyyy_dddd_aaaa_yyyy_;;;;  _////_**** _dddd_aaaa_yyyy_ssss _ssss_iiii_nnnn_cccc_eeee _JJJJ_aaaa_nnnn_uuuu_aaaa_rrrr_yyyy _1111 _---- _[[[[_0000_,,,, _3333_6666_5555_]]]] _****_////
               _iiii_nnnn_tttt  _tttt_mmmm______iiii_ssss_dddd_ssss_tttt_;;;; _////_**** _ffff_llll_aaaa_gggg _ffff_oooo_rrrr _aaaa_llll_tttt_eeee_rrrr_nnnn_aaaa_tttt_eeee _dddd_aaaa_yyyy_llll_iiii_gggg_hhhh_tttt _****_////
                                   _////_**** _ssss_aaaa_vvvv_iiii_nnnn_gggg_ssss _tttt_iiii_mmmm_eeee _****_////
          _}}}}_;;;;

     The value of _tttt_mmmm______iiii_ssss_dddd_ssss_tttt is positive if daylight savings time is in effect,
     zero if daylight savings time is not in effect, and negative if the
     information is not available. (Previously, the value of _tttt_mmmm______iiii_ssss_dddd_ssss_tttt was
     defined as non-zero if daylight savings time was in effect.)

     _cccc_tttt_iiii_mmmm_eeee, _gggg_mmmm_tttt_iiii_mmmm_eeee, _aaaa_ssss_cccc_tttt_iiii_mmmm_eeee, and _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee all return pointers to static data
     which are overwritten on each call.  Reentrant versions of these
     functions are also available as _n_a_m_e______rrrr.  The parameter _bbbb_uuuu_ffff to _aaaa_ssss_cccc_tttt_iiii_mmmm_eeee______rrrr
     and _cccc_tttt_iiii_mmmm_eeee______rrrr specify a character buffer where the resultant string should
     be placed.  This buffer should be at least 26 characters long.  The
     parameter _rrrr_eeee_ssss_uuuu_llll_tttt to _gggg_mmmm_tttt_iiii_mmmm_eeee______rrrr and _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee______rrrr points to where the
     resultant broken-down time is placed.  These two functions always return
     a pointer to that same structure.

     The external _tttt_iiii_mmmm_eeee______tttt variable _aaaa_llll_tttt_zzzz_oooo_nnnn_eeee contains the difference, in seconds,
     between Coordinated Universal Time and the alternate time zone.  The
     external variable _tttt_iiii_mmmm_eeee_zzzz_oooo_nnnn_eeee contains the difference, in seconds, between
     UTC and local standard time. The external variable _dddd_aaaa_yyyy_llll_iiii_gggg_hhhh_tttt indicates
     whether time should reflect daylight savings time.  Both _tttt_iiii_mmmm_eeee_zzzz_oooo_nnnn_eeee and
     _aaaa_llll_tttt_zzzz_oooo_nnnn_eeee default to 0 (UTC).  The external variable _dddd_aaaa_yyyy_llll_iiii_gggg_hhhh_tttt is non-zero
     if an alternate time zone exists.  The time zone names are contained in
     the external variable _tttt_zzzz_nnnn_aaaa_mmmm_eeee, which by default is set to:

          _cccc_hhhh_aaaa_rrrr _****_tttt_zzzz_nnnn_aaaa_mmmm_eeee_[[[[_2222_]]]] _==== _{{{{ _""""_GGGG_MMMM_TTTT_""""_,,,, _""""   _"""" _}}}}_;;;;

     Each of these global variables have an alias which makes the variable
     names ANSI compliant.  The alias refers to the same storage location and
     is identified by preceding the name of the variable with an underscore
     '_'.

     These functions know about the peculiarities of this conversion for
     various time periods for the U.S.  (specifically, the years 1974, 1975,
     and 1987).  They will handle the new daylight savings time starting with
     the first Sunday in April, 1987.




                                                                        PPPPaaaaggggeeee 2222






ccccttttiiiimmmmeeee((((3333CCCC))))                                                            ccccttttiiiimmmmeeee((((3333CCCC))))



     _tttt_zzzz_ssss_eeee_tttt uses the contents of the environment variable _TTTT_ZZZZ to override the
     value of the different external variables.  It also sets the external
     variable _dddd_aaaa_yyyy_llll_iiii_gggg_hhhh_tttt to zero if Daylight Savings Time conversions should
     never be applied for the time zone in use; otherwise, non-zero.  _tttt_zzzz_ssss_eeee_tttt is
     called by _aaaa_ssss_cccc_tttt_iiii_mmmm_eeee and _aaaa_ssss_cccc_tttt_iiii_mmmm_eeee______rrrr and may also be called by the user.  See
     _eeee_nnnn_vvvv_iiii_rrrr_oooo_nnnn(5) for a description of the _TTTT_ZZZZ environment variable.

     _tttt_zzzz_ssss_eeee_tttt scans the contents of the environment variable and assigns the
     different fields to the respective variable.  For example, the most
     complete setting for New Jersey in 1986 could be

          _EEEE_SSSS_TTTT_5555_EEEE_DDDD_TTTT_4444_,,,,_1111_1111_6666_////_2222_::::_0000_0000_::::_0000_0000_,,,,_2222_9999_8888_////_2222_::::_0000_0000_::::_0000_0000

     or simply

           _EEEE_SSSS_TTTT_5555_EEEE_DDDD_TTTT

     An example of a southern hemisphere setting such as the Cook Islands
     could be

           _KKKK_DDDD_TTTT_9999_::::_3333_0000_KKKK_SSSS_TTTT_1111_0000_::::_0000_0000_,,,,_6666_3333_////_5555_::::_0000_0000_,,,,_3333_0000_2222_////_2222_0000_::::_0000_0000

     In the longer version of the New Jersey example of _TTTT_ZZZZ_,,,, _tttt_zzzz_nnnn_aaaa_mmmm_eeee[_0] is EST,
     _tttt_iiii_mmmm_eeee_zzzz_oooo_nnnn_eeee will be set to 5*60*60, _tttt_zzzz_nnnn_aaaa_mmmm_eeee[_1] is EDT, _aaaa_llll_tttt_zzzz_oooo_nnnn_eeee will be set to
     4*60*60, the starting date of the alternate time zone is the 117th day at
     2 AM, the ending date of the alternate time zone is the 299th day at 2 AM
     (using zero-based Julian days), and _dddd_aaaa_yyyy_llll_iiii_gggg_hhhh_tttt will be set positive.
     Starting and ending times are relative to the alternate time zone.  If
     the alternate time zone start and end dates and the time are not
     provided, the days for the United States that year will be used and the
     time will be 2 AM.  If the start and end dates are provided but the time
     is not provided, the time will be 2 AM.  _tttt_zzzz_ssss_eeee_tttt changes the values of the
     external variables _tttt_iiii_mmmm_eeee_zzzz_oooo_nnnn_eeee, _aaaa_llll_tttt_zzzz_oooo_nnnn_eeee, _dddd_aaaa_yyyy_llll_iiii_gggg_hhhh_tttt, and _tttt_zzzz_nnnn_aaaa_mmmm_eeee.  _cccc_tttt_iiii_mmmm_eeee,
     _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee, _mmmm_kkkk_tttt_iiii_mmmm_eeee, and _ssss_tttt_rrrr_ffff_tttt_iiii_mmmm_eeee will also update these external variables
     as if they had called _tttt_zzzz_ssss_eeee_tttt at the time specified by the _tttt_iiii_mmmm_eeee______tttt or _ssss_tttt_rrrr_uuuu_cccc_tttt
     _tttt_mmmm value that they are converting.
     Note that in most installations, _TTTT_ZZZZ is set to the correct value by
     default when the user logs on, via the local _////_eeee_tttt_cccc_////_pppp_rrrr_oooo_ffff_iiii_llll_eeee file [see
     _pppp_rrrr_oooo_ffff_iiii_llll_eeee(4) and _tttt_iiii_mmmm_eeee_zzzz_oooo_nnnn_eeee(4)].

EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
     This example returns a string containing the current date and time using
     any locally set timezone information:
               _tttt_iiii_mmmm_eeee______tttt _tttt_;;;;
               _cccc_hhhh_aaaa_rrrr _****_cccc_;;;;
               _tttt _==== _tttt_iiii_mmmm_eeee_((((_NNNN_UUUU_LLLL_LLLL_))))_;;;;
               _cccc _==== _aaaa_ssss_cccc_tttt_iiii_mmmm_eeee_((((_llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee_((((_&&&&_tttt_))))_))))_;;;;






                                                                        PPPPaaaaggggeeee 3333






ccccttttiiiimmmmeeee((((3333CCCC))))                                                            ccccttttiiiimmmmeeee((((3333CCCC))))



DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
FFFFIIIILLLLEEEESSSS
     _////_uuuu_ssss_rrrr_////_llll_iiii_bbbb_////_llll_oooo_cccc_aaaa_llll_eeee_////_l_a_n_g_u_a_g_e_////_LLLL_CCCC______TTTT_IIII_MMMM_EEEE - file containing locale specific date
     and time information

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _tttt_iiii_mmmm_eeee(2), _gggg_eeee_tttt_eeee_nnnn_vvvv(3C), _mmmm_kkkk_tttt_iiii_mmmm_eeee(3C), _pppp_uuuu_tttt_eeee_nnnn_vvvv(3C), _pppp_rrrr_iiii_nnnn_tttt_ffff(3S), _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee(3C),
     _ssss_tttt_rrrr_ffff_tttt_iiii_mmmm_eeee(3C), _cccc_ffff_tttt_iiii_mmmm_eeee(4), _pppp_rrrr_oooo_ffff_iiii_llll_eeee(4), _tttt_iiii_mmmm_eeee_zzzz_oooo_nnnn_eeee(4), _eeee_nnnn_vvvv_iiii_rrrr_oooo_nnnn(5).

NNNNOOOOTTTTEEEESSSS
     The return values for _cccc_tttt_iiii_mmmm_eeee, _llll_oooo_cccc_aaaa_llll_tttt_iiii_mmmm_eeee, and _gggg_mmmm_tttt_iiii_mmmm_eeee point to static data
     whose content is overwritten by each call.

     Setting the time during the interval of change from _tttt_iiii_mmmm_eeee_zzzz_oooo_nnnn_eeee to _aaaa_llll_tttt_zzzz_oooo_nnnn_eeee
     or vice versa can produce unpredictable results.  The system
     administrator must change the Julian start and end days annually.







































                                                                        PPPPaaaaggggeeee 4444